TPUG - Toronto PET Users Group/TPUG Users Group CD/TPUG Users Group CD.iso/AMIGA/(A)TB/(A)TBJ.ADF/HEX/Hex.doc

Text File | 1990-12-23 | 18KB | 510 lines

---------------------------------------------------------------------
                             #   # ##### #   #
                             #   # #      # #
                             ##### ###     #
                             #   # #      # #
                             #   # ##### #   #
---------------------------------------------------------------------

                      Hex V1.0, Copyright (c) 1990 by

                             Nicola Salmoria
                             Via Piemonte 11
                             53100 Siena  ITALY

                            All rights reserved.


You can contact me on:
MC-Link:      [phone]      my code is MC6489

Voice:        [phone]

You can try to contact me on FidoNet, but it's unlikely you'll get an
answer, 'cos there's yet no Fido node in Siena. Maybe in the future.


This program is SHAREWARE. Copy it as much as you can (provided no
charge is made and the archive is left intact). It can be included,
with the same restrictions, in any commercial program without the
written permission of the author.
Contributions will be greatly appreciated and will help me support
Hex in the future as well as develop new programs. Suggested
contribution is $15. Hex development took 4 months. I spent much time
on it, and I'd like to be rewarded for my work.
Keep one thing in mind: I will probably add new features to Hex, but
I will NOT release a new version until I get enough feedback. So you
know what to do.


IMPORTANT NOTE: Hex has some unique features difficult to understand
or to even know about without reading this doc file. If you're too
lazy to read it all, you should read at least the 'Editing &
keyboard' chapter, plus the explanations of the menu items you don't
understand.

WARNING: This program in the wrong hands may be a lethal weapon! Use
at your own risk. Anyway, Hex is provided "AS IS", without warranty
of any kind, either expressed or implied. The author will never be
liable for any loss of data, disk damage, computer explosion,
earthquake, alien invasion, or anything else.

REMEMBER: It is both immoral and illegal to modify someone else's
programs and redistribute them. All such changes should be considered
strictly for personal use. If you want to let the rest of the world
know about some nice changes you've devised, I think it may be
considered acceptable to spread a text file explaining what to change
(like I do with keymaps later on).


--------
Overview
--------

Hex is a file-based (as opposed to sector-based, like NewZAP) binary
file editor. This means that the file is loaded in memory all at
once, edited there and saved at the end. There are advantages and
disadvantages in both approaches: sector-based editors depend heavily
on device speed in operations like search; on the other hand, file
based-ones take longer to display the file for the first time, 'cos
they have to load it all. Moreover, file-based editors need more
memory, and it may be impossible to load very large files. Hex uses
the same text routines of MiniView80. This means it's got (one of)
the fastest and smoothest screen rendering ever seen in a file
editor.


---------------
Acknowledgement
---------------

I'd like to thank the following people for beta-testing and
suggestions:
Federico Giannici
Marco Ciuchini
Antonio Rossi
Massimiliano Marras
Angelo Mariani


-------
Loading
-------

From WorkBench, double-click on Hex icon. You can use extended
selection: click on Hex icon, then press SHIFT and double-click on
the file icon.

From CLI, syntax is:
Hex [filename] [NODETACH]
If you specify a file name, it will be loaded on startup.
By default, Hex detaches from the current CLI. You can disable this
feature with the switch NODETACH. It may be useful if you execute Hex
from one of that nice directory utilities.

IMPORTANT NOTE: To load Hex, the file 'req.library' must be in your
LIBS: directory. Req.library is a freely distributable library by
C.W.Fox and Bruce Dawson. If you are a programmer, you may want to
take a look at it. It features the BEST file requester I have ever
seen and many other nice functions.


-----------
The gadgets
-----------

Many hex functions are obtained thru the use of gadgets. Most of them
can be operated also with menus. Of course selecting a menu is less
handy than directly clicking in a gadget; menu operations are there
mostly to provide keyboard shortcuts.

Search gadgets:
---------------
In the 'Search' box there are many gadgets, all obviously related to
the search functions. There are three boxes near to the words
'Search', 'Hex', 'Text'. Only one of them is selected, and indicates
which search mode is currently active. You can click on them to
quickly change search mode. If a match is found, cursor is placed at
the start of it, and edit mode is changed to the corresponding one.

String
         Search for a given string. Click in the string gadget below
and enter the text you want to search for. When you press return,
search will start at cursor position.

A=a
         Search can be case sensitive or case unsensitive; you can
switch the flag with this gadget.

Hex
         Search for a sequence of bytes you specify via their
hexadecimal notation. Click in the string gadget below and enter the
byte sequence you want to search. You can enter data as xx xx xx,
xxxxxxxx, xxxx xx xxxxxx, anyway you want, provided between two blank
spaces there is an even number of characters.

CAL
         Imports in the hex gadget the value currently displayed on
the calculator display. A leading zero is added if needed.

Text
         This is a special feature: it searches the file for
occurrencies of at least eight 'good' ASCII characters. It is useful
to quickly locate message strings in a file. When this box is
selected, use 'Continue' to scan the file.

Continue
         Continues the search from the new cursor position.

<< and >>
         Specify the search direction.


Other gadgets:
--------------
Start and End
         These two behave differently if you are editing a file or
GRABbing memory (see below). In file mode, 'Start' is always zero and
'End' indicates the last byte of the file (or, if you prefer, the
file length MINUS ONE). In memory mode, they indicate the start and
end of the memory grabbed. You can change the value contained in
these gadgets: the file will be modified accordingly, if possible.
You can enlarge or shrink a file, or change the 'window' on the
memory. To add bytes at the start of the file, simply insert a
negative value. Note that when you change the 'Start' gadget in file
mode, it is reset to zero and the 'End' value is changed accordingly.
         If you press SHIFT-Return in one of the gadgets, the other
one is activated. This is an easy way to change start and end
together. It's main use is to completely change the portion of memory
grabbed.

Position
         Reports the position occupied by the cursor in the file.
Modify its value to jump to a specific location.

Editing
         Shows which side of the display you are editing: ASCII or
HEX. This gadget exists only in 'Hex/ASCII' display mode, in 'Only
ASCII' it is replaced by 'Value', which reports the hex value of the
byte the cursor is on. You can modify this value, so you don't have
to change the display mode to insert an hex value in the middle of an
ASCII string.

UNDO and REDO
         Self explanatory. Hex features a multi-level undo/redo
(currently max undo level is 256).



---------
The menus
---------

NOTE: I won't repeat it for every function, but every time you do
something which would mean losing the current data, a requester will
appear asking if you want to save the file, continue anyway, or
cancel the operation.

Project:
--------
About
         The usual information about the program.

New
         Creates a new file. The current file is cleared, and the
gadget 'End' is activated. Type there the size MINUS ONE of the file
you want to create.

Open
         Loads a new file. The req.library file requester will pop
up, asking you to select a file to load.

Save
         Saves the file. Again the req.library requester will come,
asking the filename with which the file will be saved. If you want to
overwrite the previous version, simply click on OK.

GRAB Memory
         WARNING: this function is dedicated to the expert users.
The current file is cleared, and the 'Start' gadget is activated.
Type the start address of the memory you want to grab. If you specify
a valid number, the 'End' gadget wil activate. Type the end address,
and there you go! Hex will try to AllocAbs() the memory you specify:
result of that operation is displayed in the menu bar. If the buffer
couldn't be allocated, the 'Editable file?' flag (see below) is
turned off, just to provide more protection.
         I deliberately don't check if the memory addresses you
specify are locations you are allowed to access. I do so to let you
GRAB portions of memory like system ROMs, expansion ROMs, memory
removed from the system lists, and so on. For example, (my version
of) the A2620 board allocates its ROMs at F80000-F87DEF.
         Please note that not only you can crash your system WRITING
somewhere you shouldn't, but also simply READING some forbidden
locations. Just to give you an idea, on my system locations between
C80000 and DFFFFF must be avoided.

Print
         Sends current file to PRT:. If replacement char is '╖', it
is replaced with '.'; char set 'all chars' is not supported, replaced
with 'only printable'.

Print marked
         Sends to PRT: the portion of the file between the two mark
positions. It doesn't matter which of the two comes before. Note that
the two marks are always set somewhere - if you don't initialize
them, they will point one to the start and the other to the end of
the file.

Iconify
         Iconifies Hex. Memory is freed, buffer purged and screen
closed - and a small window is opened in the WorkBench screen. To
reactivate Hex, press the right button when that window is active.
You can quit definitively with the close gadget.

Quit
         Guess what?


Environment:
------------
Palette
         Invokes req.library color requester.

Display
         Two modes are available: Hex/ASCII which prints 16 bytes per
row, showed in hexadecimal long words and in plain ASCII. Only ASCII
prints 48 bytes per row, only as ASCII characters.

Char set
         Selects which characters should be filtered out in the ASCII
dump. 'All chars' means no substitutions are made; 'Only printable'
means only chars $20-$7F and $A0-$FF are showed; 'Only $20-$7F' is
self explanatory.

Replacement char
         Specifies the char with which filtered chars are
substituted. Choice is between ' ' (space) ,'.' (full stop) and '╖'
(?? code $B7)

Load settings
         Loads current settings from 'hex.config'.

Save settings
         Saves current settings to 'hex.config'. On future loadings
of Hex, the saved settings will be automatically re-loaded. Settings
saved are: Palette, Display, Char set, Replacement char,
Backspace=undo, Ignore case, Overwrite NULLs, search mode, Iconify
window position.

Default settings
         Uses the built-in settings.


Edit:
-----
Undo/Redo
         Same as the corresponding gadgets.

Backspace = undo?
         Selects if pressing the backspace key (top right of
keyboard) should be the same as selecting Undo (or pressing its
keyboard shortcut).

Change file start
         All this item does is activate the 'Start' gadget.

Start at cursor pos
         Easy way to make a file begin at the cursor position
(instead of selecting 'Start', and writing there the correct value).

Change file end
         Activates the 'End' gadget.

End at cursor pos
         Faster way to specify file's end position.

Switch edit mode / Change value
         Same as the corresponding gadgets.

Overwrite NULLs?
         Specifies if in ASCII edit bytes which are zero can be
modified. When you replace text strings in an executable, e.g. the
names of the menus, it is VERY important the new strings don't exceed
previous lengths. Since C strings are NULL-terminated, when this item
is de-selected, you won't be able to write past the max length
allowed.

Editable file?
         If this is not checked, the file cannot be modified in any
way. This flag is turned OFF when you GRAB a portion of memory which
can't be allocated; it's turned ON every time the buffer is clear
(Load, New)


Search:
-------
Search string
         Activates the 'search string' gadget.

Search hex
         Activates the 'search hex' gadget.

Search text
         Searches for text, as specified before. To continue search,
you can use 'continue' as well as this item again.

Ignore case?
         Switches the case dependancy flag. Equivalent to the 'A=a'
gadget.

Direction
         Selects the search direction. Equivalent to the
corresponding gadgets.

Continue search
         Repeats last search made. The same as the 'continue' gadget.


Move:
-----
Top
         Jumps to start of file.

Bottom
         Jumps to end of file.

Any position
         Activates the 'position' gadget.

Mark location n
         Set the mark 'n' to the present cursor position. Marks are
used also by the 'print marked' function.

Jump to mark n
         Jumps to mark 'n'. If the mark wasn't set, jump to start/end
of file.


The calculator
--------------

NOTE: on 640x200 screens this feature is not available. NTSC users
should use an interlaced screen.

On the top right corner of the screen there is a simple calculator.
It's use is fairly simple, being like any usual calculator. I want to
point out that you can use both the mouse in the intuitive way and
the keyboard. In that case, here are the equivalents to the
not-so-intuitive keys:
.                = +/-
$ or H           = Hex
# or T           = Dec
Del or BackSpace = Clear
Help             = On/Off

Moreover, the grey keys on the keypad act as the keys A-F. The same
keys SHIFTed or CAPS LOCKed represent the four operations and the
Hex/Dec gadgets. Note that if you press SHIFT while CAPS LOCK is lit,
you get A-F again.

One nice thing to note is that the calculator is a stand-alone task,
separated from the main program; this means it is ALWAYS available,
even when Hex is doing something else like displaying a requester or
loading a file from disk. Another important thing is that the
calculator runs on its own window; so don't panic if when you use it
you lose the menus - just click in the main window and you'll get
them back.


Moving around
-------------

There are many ways to move through the file. Clicking on any valid
position will put the cursor there; if you keep the left button
pressed and move the pointer, the cursor will follow you. If you move
the pointer to the extreme top or bottom of screen, you'll scroll
through the file. Edit mode changes correspondingly to where you
click.

To fast reach a known position you can use the Jump command or the
scroll bar on the right of the screen.

Using keyboard, cursor keys in combination with shift, alt, ctrl have
many effects. Plain cursor keys move the cursor, and scroll file, in
the intuitive way; shift-up and shift-down move 8 positions at a time
and scroll faster; alt-up and alt-down move one page at a time; any
qualifier together with left/right moves to begin/end of current
line. Ctrl-up and ctrl-down move to start and end of file.


Editing & keyboard
------------------

In ASCII edit, simply type what you like. Note that Return generates
a LF ($0A), while Enter a CR ($0D). Moreover, SHIFT-Return generates
a NULL. This is very useful to terminate strings without having to
switch to HEX edit. In HEX edit, type couples of hex chars. If you
mistake the first number, SPACE will cancel it. Please note that you
won't see the first number you type: only the full byte is
substituded after you enter the couple of chars.

Hex uses RawKeyConvert(), so custom keymaps ARE supported.
There is an exception: while in hex edit, grey keys on the numeric
keypad behave like keys A-F. This allows very fast input of data.
This is the layout of the keypad:

       +-----+-----+-----+-----+
       |     |     |     |     |
       |  A  |  B  |  C  |  D  |
       |     |     |     |     |
       +-----+-----+-----+-----+
       |     |     |     |     |
       |  7  |  8  |  9  |  E  |
       |     |     |     |     |
       +-----+-----+-----+-----+
       |     |     |     |     |
       |  4  |  5  |  6  |  F  |
       |     |     |     |     |
       +-----+-----+-----+-----+
       |     |     |     |     |
       |  1  |  2  |  3  |  E  |
       |     |     |     |  n  |
       +-----+-----+-----+  t  |
       |           |     |  e  |
       |     0     |  .  |  r  |
       |           |     |     |
       +-----------+-----+-----+

Such feature would be handy also in the input gadgets; however, they
are handled by Intuition, so a keymap is needed. I have provided a
file called 'h', which is a custom keymap you should put in
DEVS:keymaps. However, if you like, you can modify your keymap and
use it with hex or anywhere you like. Here is how to proceed:

- Load Hex (this is the least you could expect!).
- OPEN DEVS:keymaps/your_keymap.
- JUMP to 20F. There should be a '-' there.
- Modify the '-' to 'E'.
- JUMP to 24F. This is the top-left key in the keypad.
- Modify it to 'A'.
- Go to 253. Modify to 'B'.
- Go to 257. Modify to 'C'.
- Go to 25B. Modify to 'D'.
- Go to 25F. Modify to 'F'.
- SEARCH for '?~'. After these two chars, there should be the name of
  the keyboard. Replace it with 'h'. If the keymap name is longer
  then one char, remember to put a NULL after h.
- SAVE as DEVS:keymaps/h

All done. Hex will automatically load DEVS:keymaps/h on startup.


Note about requesters
---------------------

You don't need mouse to reply to req.library requesters. There's a
whole range of keys you can use, the easiest to remember are:
L for the left gadget
M for the middle gadget
R for the right gadget